<!doctype html>
<html lang="en" class="page-type-section">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>User-defined directive (&lt;@...&gt;) - FreeMarker 手册</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker 手册">
<meta property="og:title" content="User-defined directive (&lt;@...&gt;)">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://freemarker.org/docs/ref_directive_userDefined.html">
<link rel="canoical" href="http://freemarker.org/docs/ref_directive_userDefined.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css">
</head>
<body itemscope itemtype="https://schema.org/Code">
    <meta itemprop="url" content="http://freemarker.org/docs/">
    <meta itemprop="name" content="FreeMarker 手册">

  <!--[if lte IE 9]>
  <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
  <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner">            <img itemprop="image" src="logo.png" alt="FreeMarker">
</a><ul class="tabs"><li><a href="http://freemarker.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="http://freemarker.org/docs/api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://sourceforge.net/p/freemarker/bugs/new/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="toc.html" class="navigation-header">Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="toc.html"><span itemprop="name">FreeMarker 手册</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref.html"><span itemprop="name">模板语言参考 </span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directives.html"><span itemprop="name">指令参考</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directive_userDefined.html"><span itemprop="name">User-defined directive (&lt;@...&gt;)</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div>    <div class="main-content site-width">
      <div class="content-wrapper">
  <div id="table-of-contents-wrapper" class="col-left">
      <script>var breadcrumb = ["FreeMarker 手册","模板语言参考 ","指令参考","User-defined directive (<@...>)"];</script>
      <script src="toc.js"></script>
      <script src="docgen-resources/main.min.js"></script>
  </div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="ref_directive_t.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_visit.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="ref_directive_userDefined" itemprop="headline">User-defined directive (&lt;@...&gt;)</h1>
</div></div><div class="page-menu">
<div class="page-menu-title">Page Contents</div>
<ul><li><a class="page-menu-link" href="#autoid_119" data-menu-target="autoid_119">概要</a></li><li><a class="page-menu-link" href="#autoid_120" data-menu-target="autoid_120">描述</a><ul><li><a class="page-menu-link" href="#ref_directive_userDefined_entTag" data-menu-target="ref_directive_userDefined_entTag">结束标签</a></li><li><a class="page-menu-link" href="#ref_directive_userDefined_loopVar" data-menu-target="ref_directive_userDefined_loopVar">循环变量</a></li><li><a class="page-menu-link" href="#ref_directive_userDefined_positionalParam" data-menu-target="ref_directive_userDefined_positionalParam">位置参数传递</a></li></ul></li></ul> </div><a name="ref.directive.userDefined"></a>
          



<h2 class="content-header header-section2" id="autoid_119">概要</h2>


          
<pre class="metaTemplate">
<code class="inline-code">&lt;@<em class="code-color">user_def_dir_exp</em> <em class="code-color">param1</em>=<em class="code-color">val1</em> <em class="code-color">param2</em>=<em class="code-color">val2</em> <em class="code-color">...</em> <em class="code-color">paramN</em>=<em class="code-color">valN</em>/&gt;</code>
(注意 XML 风格， <code class="inline-code">/</code> 在 <code class="inline-code">&gt;</code> 之前)  
或如果需要循环变量 (<a href="#ref_directive_userDefined_loopVar">更多细节...</a>)
<code class="inline-code">&lt;@<em class="code-color">user_def_dir_exp</em> <em class="code-color">param1</em>=<em class="code-color">val1</em> <em class="code-color">param2</em>=<em class="code-color">val2</em> <em class="code-color">...</em> <em class="code-color">paramN</em>=<em class="code-color">valN</em> ; <em class="code-color">lv1</em>, <em class="code-color">lv2</em>, <em class="code-color">...</em>, <em class="code-color">lvN</em>/&gt;</code>

或和上面两个相同但是使用结束标签 (<a href="#ref_directive_userDefined_entTag">更多细节...</a>):

<code class="inline-code">&lt;@<em class="code-color">user_def_dir_exp</em> <em class="code-color">...</em>&gt;
  ...
&lt;/@<em class="code-color">user_def_dir_exp</em>&gt;</code>
或
<code class="inline-code">&lt;@<em class="code-color">user_def_dir_exp</em> <em class="code-color">...</em>&gt;
  ...
&lt;/@&gt;</code>

或和上面的相同但是使用位置参数传递 (<a href="#ref_directive_userDefined_positionalParam">更多细节...</a>):

<code class="inline-code">&lt;@<em class="code-color">user</em> <em class="code-color">val1</em>, <em class="code-color">val2</em>, <em class="code-color">...</em>, <em class="code-color">valN</em>/&gt;</code>
等...
</pre>


          <p>这里：</p>

          <ul>
            <li>
              <code class="inline-code"><em class="code-color">user_def_dir_exp</em></code>：
			  表达式算作是自定义指令(比如宏)，将会被调用。
            </li>

            <li>
              <code class="inline-code"><em class="code-color">param1</em></code>，
              <code class="inline-code"><em class="code-color">param2</em></code>等...：
			  参数的名称，它们 <em>不是</em> 表达式。
            </li>

            <li>
              <code class="inline-code"><em class="code-color">val1</em></code>，
              <code class="inline-code"><em class="code-color">val2</em></code>等...：
			  参数的值，它们 <em>是</em> 表达式。
            </li>

            <li>
              <code class="inline-code"><em class="code-color">lv1</em></code>，
              <code class="inline-code"><em class="code-color">lv2</em></code>等...：
			  <a href="dgui_misc_var.html">循环变量</a> 的名称，
			  它们 <em>不是</em> 表达式。
            </li>
          </ul>

          <p>参数的数量可以是0(也就是没有参数)。</p>

          <p>参数的顺序并不重要(除非你使用了位置参数传递)。
		  参数名称必须唯一。在参数名中小写和大写的字母被认为是不同的字母
		  (也就是 <code class="inline-code">Color</code> 和 <code class="inline-code">color</code> 是不同的)。</p>
        
          



<h2 class="content-header header-section2" id="autoid_120">描述</h2>


          <p>这将调用用户自定义指令，比如宏。参数的含义，
		  支持和需要的参数的设置依赖于具体的自定义指令。</p>

          <p>你可以阅读 <a href="dgui_misc_userdefdir.html">自定义指令</a>。</p>

          <p>示例1：调用存储在变量
          <code class="inline-code">html_escape</code> 中的指令：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;@html_escape&gt;
  a &lt; b
  Romeo &amp; Juliet
&lt;/@html_escape&gt;</pre></div>

          <p>将会输出：</p>

          

<div class="code-wrapper"><pre class="code-block code-output">  a &amp;lt; b
  Romeo &amp;amp; Juliet</pre></div>

          <p>示例2：调用有参数的宏：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;@list items=[&quot;mouse&quot;, &quot;elephant&quot;, &quot;python&quot;] title=&quot;Animals&quot;/&gt;
<em>...</em>
&lt;#macro list title items&gt;
  &lt;p&gt;${title?cap_first}:
  &lt;ul&gt;
    &lt;#list items as x&gt;
      &lt;li&gt;${x?cap_first}
    &lt;/#list&gt;
  &lt;/ul&gt;
&lt;/#macro&gt;</pre></div>

          <p>将会输出：</p>

          

<div class="code-wrapper"><pre class="code-block code-output">  &lt;p&gt;Animals:
  &lt;ul&gt;
      &lt;li&gt;Mouse
      &lt;li&gt;Elephant
      &lt;li&gt;Python
  &lt;/ul&gt;
  
<em>...</em></pre></div>

          
            



<h3 class="content-header header-section3" id="ref_directive_userDefined_entTag">结束标签</h3>


            <p>你可以在 <a href="gloss.html#gloss.endTag">结束标签</a> 中忽略 
			<code class="inline-code"><em class="code-color">user_def_dir_exp</em></code>。
			也就是说，你可以写 <code class="inline-code">&lt;/@&gt;</code> 来替代 
			<code class="inline-code">&lt;/@<em class="code-color">anything</em>&gt;</code>。
			这个规则当表达式 <code class="inline-code"><em class="code-color">user_def_dir_exp</em></code> 
			太复杂时非常有用，因为你不需要在结束标签中重复表达式。
			此外，如果表达式包含比简单变量名和点还多的表达式，你就不能再重复它们了。比如，
			<code class="inline-code">&lt;@a_hash[a_method()]&gt;<em class="code-color">...</em>&lt;/@a_hash[a_method()]&gt;</code> 就是错的，你必须写为 
			<code class="inline-code">&lt;@a_hash[a_method()]&gt;<em class="code-color">...</em>&lt;/@&gt;</code>。
			但是 
			<code class="inline-code">&lt;@a_hash.foo&gt;<em class="code-color">...</em>&lt;/@a_hash.foo&gt;</code> 
			是可以的。</p>
          

          
            



<h3 class="content-header header-section3" id="ref_directive_userDefined_loopVar">循环变量</h3>


            <p>一些自定义指令创建循环变量(和 <code class="inline-code">list</code> 指令相似)。
			正如预定义指令(如 <code class="inline-code">list</code>)一样，当你调用这个指令
			(如 <code class="inline-code">&lt;#list foos as
            foo&gt;<em class="code-color">...</em>&lt;/#list&gt;</code>中的 
			<code class="inline-code">foo</code>)时循环变量的 <em>名称</em> 就给定了，
			而变量的 <em>值</em> 是由指令本身设置的。
			在自定义指令的情形下，语法是循环变量的名称在分号之后给定。比如：</p>

            

<div class="code-wrapper"><pre class="code-block code-template">&lt;@myRepeatMacro count=4 ; <strong>x, last</strong>&gt;
  ${<strong>x</strong>}. Something... &lt;#if <strong>last</strong>&gt; This was the last!&lt;/#if&gt;
&lt;/@myRepeatMacro&gt;</pre></div>

            <p>请注意，由自定义指令创建的循环变量数量和分号之后指定的循环变量数量需要不匹配。
			也就是说，如果你对重复是否是最后一个不感兴趣，你可以简单来写：</p>

            

<div class="code-wrapper"><pre class="code-block code-template">&lt;@myRepeatMacro count=4 ; <strong>x</strong>&gt;
  ${<strong>x</strong>}. Something...
&lt;/@myRepeatMacro&gt;</pre></div>

            <p>或者你可以：</p>

            

<div class="code-wrapper"><pre class="code-block code-template">&lt;@myRepeatMacro count=4&gt;
  Something...
&lt;/@myRepeatMacro&gt;</pre></div>

            <p>此外，如果你在分号之后指定更多循环变量而不是自定义指令创建的，
			也不会引起错误，只是最后的循环变量不能被创建
			(也就是在嵌套内容中那些将是未定义的)。尝试使用未定义的循环变量，
			就会引起错误(除非你使用如 <code class="inline-code">?default</code> 这样的内建函数)，
			因为你尝试访问了一个不存在的变量。</p>

            <p>参考 <a href="dgui_misc_userdefdir.html">自定义指令</a> 来获取更多内容。</p>
          

          
            



<h3 class="content-header header-section3" id="ref_directive_userDefined_positionalParam">位置参数传递</h3>


            

            <p>位置参数传递(如<code class="inline-code">&lt;@heading &quot;Preface&quot;, 1/&gt;</code>)
			是正常命名参数传递(如<code class="inline-code">&lt;@heading title=&quot;Preface&quot; level=1/&gt;</code>)
			的速记形式，这里忽略了参数的名称。如果自定义指令只有一个参数，
			或者对于经常使用的自定义指令它参数的顺序很好记忆，速记形式应该被应用。
			为了应用这种形式，你不得不了解声明的命名参数的顺序(如果指令只有一个参数这是很琐碎的)。
			也就是，如果 <code class="inline-code">heading</code> 被创建为 <code class="inline-code">&lt;#macro heading title
            level&gt;<em class="code-color">...</em></code>，
			那么 <code class="inline-code">&lt;@heading &quot;Preface&quot;, 1/&gt;</code> 和 
			<code class="inline-code">&lt;@heading title=&quot;Preface&quot; level=1/&gt;</code>
			(或 <code class="inline-code">&lt;@heading level=1 title=&quot;Preface&quot;/&gt;</code>；
			如果你使用参数名称，那顺序就不重要了)是相等的。
			要注意位置参数传递现在仅仅支持宏定义。</p>
          
        <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_directive_t.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_visit.html"><span>Next</span></a></div></div></div></div>      </div>
    </div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/index.html">What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html">About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/nanlei/freemarker/tree/manual-zh-2.3-gae/src/manual">Chinese Manual on Github</a></li><li><a href="https://github.com/freemarker/freemarker">FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker">Follow us on Twitter</a></li><li><a href="https://sourceforge.net/p/freemarker/bugs/new/">Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker">Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html">Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"><p><span class="generated-for-product">Generated for: Freemarker 2.3.23</span><span class="last-updated"> Last generated:
<time itemprop="dateModified" datetime="2015-09-18T14:38:51Z" title="Friday, September 18, 2015 2:38:51 PM GMT">2015-09-18 14:38:51 GMT</time></span></p> <p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2015
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="http://freemarker.org">The FreeMarker Project</a>. All rights reserved. </p>
</div></div></div></body>
</html>
